home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Aminet 2
/
Aminet AMIGA CDROM (1994)(Walnut Creek)[Feb 1994][W.O. 44790-1].iso
/
Aminet
/
comm
/
term
/
ShellTerm_1_19.lha
/
ShellTerm
/
ShellTerm.DOC
< prev
next >
Wrap
Text File
|
1993-05-28
|
24KB
|
697 lines
27/05-93 ShellTerm V1.19
Updated: 05/08-92 - for version 1.01 - Preliminary docs
Updated: 06/08-92 - for version 1.02 - Preliminary docs
Updated: 08/08-92 - for version 1.03 - Almost finished docs
Updated: 11/08-92 - for version 1.04 - Release version
Updated: 14/08-92 - for version 1.05 - Bug fixes
Updated: 28/08-92 - for version 1.06 - Additions and beta testing
Updated: 30/08-92 - for version 1.07 - Additions and beta testing
Updated: 04/09-92 - for version 1.08 - Additions
Updated: 06/09-92 - for version 1.09 - Release 2
Updated: 20/10-92 - for version 1.10 - Bug fixes
Updated: 13/11-92 - for version 1.11 - Private release
Updated: 01/01-93 - for version 1.12 - Release 3
Updated: 02/01-93 - for version 1.13 - Additions
Updated: 06/02-93 - for version 1.14 - Bug fixes
Updated: 10/02-93 - for version 1.15 - Release 4. 'Feature' removed
Updated: 24/03-93 - for version 1.16 - Release 5. Major bug fix
Updated: 25/03-93 - for version 1.17 - Release 6. Additions
Updated: 22/05-93 - for version 1.18 - Additions
Updated: 27/05-93 - for version 1.18 - Release 7. Additions
Copyright (C) Tomi Blinnikka 1993, All Rights Reserved.
^^^^^^^^^^^^^^^^^^^^
This program is SHAREWARE. This means that you can copy it and give it
to all your friends, upload it to a BBS or include it in a PD-library
(FISH etc.). BUT (!!!) if you use this program frequently you must
pay $5 - $10. The other restrictions are: all of the files must be
included in their original form without additions, deletions, or
modifications of any kind and it IS NOT TO BE SOLD. THIS INCLUDES
GERMAN PD DEALERS. If you wish to use this program for commercial
purposes, you need written permission. The ShellTerm program is
provided "AS IS" without warranty of any kind, and the author is not
responsible for any damage this software may or may not do.
TABLE OF CONTENTS
~~~~~~~~~~~~~~~~~
1. What does it do?
- Short description of what this program does and/or does not do.
2. What do you need?
- A list of software/hardware needed.
3. Compatibility
- A list of computers this program works on.
4. Setting up
- Instructions on how to set up ShellTerm
5. How to run it
- Instructions on starting the program and what arguments it takes.
6. Using ShellTerm
- A short description of all functions
6.1 Main menu
6.2 Dialer menu
6.3 Preferences menu
6.4 Serial settings
6.5 Terminal settings
7. The phonebook
- Explanation of the autodialer and phonebook.
8. Hints & tips
- Hints & tips. Other programs to enhance using ShellTerm etc.
9. Problems
- Possible problems you may run into.
10. Other interesting stuff
11. Error messages
12. Versions
- A list of all versions. The newest first.
13. Future versions
14. Bugs
- List of bugs found.
15. ShareWare fee
- More information on the ShareWare fee.
16. Beta Testers
- A list of beta testers.
17. 'Registered' users
- A list of users that have payed the ShareWare fee.
18. Bug reports etc.
- How to contact the author
1. WHAT DOES IT DO?
~~~~~~~~~~~~~~~~~~~
This is a simple terminal program that runs in a CLI/Shell window. Its
primary use is with dumb terminals hooked up to an AUX-handler. This is
the reason ShellTerm doesn't open a window or screen. It uses standard
input and output. I use it as a substitute for JrComm (Copyright John
P. Radigan) when I'm using my dumb terminal (it's next to my bed... that
explains most of the stupid mistakes in these docs :) and want to call
a BBS without having to get out of bed and walk over to my Amiga.
2. WHAT DO YOU NEED?
~~~~~~~~~~~~~~~~~~~~
You'll need an Amiga computer (see compatibility list), with Kickstart
2.04 (version 37 or higher). Basically you'll also want a HAYES compatible
modem or some other piece of equipment connected to the device you specify.
3. COMPATIBILITY
~~~~~~~~~~~~~~~~
ShellTerm will work on any Commodore Amiga, running on Kickstart
2.04 or higher. This includes the following: A500(+), A600, A1000, A1200,
A2000, A2500/20, A2500/30, A3000 (16 MHz or 25 Mhz model), A4000/40. The
program SHOULD work on any upgrades (based on the Amiga Development
Guidelines, see Amiga ROM Kernel Reference Manual (Release 2): Includes
and Autodocs, introduction). ShellTerm works with all internal modems (I
have a Supra 2400zi) and extra serial boards that support the normal
device commands (I also have the A2232 serial board, but I missed a bug
with it on versions under 1.16 :).
4. SETTING UP
~~~~~~~~~~~~~
Unpack the archive somewhere and copy the files wherever you wish, but the
following is recommended:
Filename Where to copy
=====================================================================
ShellTerm C:
WatchPort C:
Scripts/ST S:
Scripts/ShellTerm-StartUp S:
ShellTerm.DOC Wherever (I use DOCS:)
ShellTerm.DOC.info Wherever (I use DOCS:)
CONTENTS Wherever
CONTENTS.info Wherever
CHANGES Wherever
CHANGES.info Wherever
If for some reason the flags of the files in the directory ShellTerm/Scripts
are not '-s--rwed', set them with the command 'Protect ShellTerm/Scripts/#?
SWERD'.
5. HOW TO RUN IT
~~~~~~~~~~~~~~~~
You can run the program from a CLI/SHELL/etc. but you can't hang an icon on
it and start it from the Workbench. I decided to drop the Workbench startup
code to make the program a little bit smaller.
To run the program, enter the following into your CLI/SHELL/etc.
1> ShellTerm FROM [FILENAME] PORT [NAME]
FROM specifies the prefs file to load and use.
PORT specifies a name for the user port to open. See HINTS &
TIPS 8.
You cannot, however, redirect input to the program, i.e. ShellTerm <NIL:
won't work. RUNning is also out of the question and will give the same
error text as redirecting.
Or then use the script in the scripts directory. It will take the following
options:
FROM [FILENAME] - Same as ShellTerm's
SCREEN [SCREEN NAME] - A name for the screen to open
(DEFAULT: ShellTerm Screen)
DEPTH [SCREEN DEPTH] - The depth of the screen to open
(DEFAULT: 1)
WINDOW [WINDOW NAME] - A name for the Shell to open
(DEFAULT: ShellTerm Window)
PORT [NAME] - Same as ShellTerm's
The ST script needs and uses a program called PSX, by Steve Tibbett, to
open the public screen. You can change this to your favorite public screen
manager if it allows you to specify the screen specifications from the
command line.
6. USING SHELLTERM
~~~~~~~~~~~~~~~~~~
Once the program has been started, anything typed into the CLI/Shell will be
sent to the selected device. If the device does not echo the characters, you
will not see anything. Normally there is a modem at the end of the device
and you will see whatever was typed. Try typing "AT <RETURN>". If it works,
you'll receive an OK text from the modem. If however there was terminal
hooked up, the characters should have appeared on its screen. If this didn't
work, please check the device's parameters from the Preferences menu.
Say the characters are messed up, try checking the serial speed.
Pressing CTRL-P will show you the menus. The CTRL-P sequence is not sent
over to the device. You will be displayed with the options available. Press
the key enclosed in parenthesis to select an item. A short description of all
items follows.
6.1 Main menu
~~~~~~~~~~~~~
Show statistics Shows how many bytes have been transferred to and
from the device.
Clear statistics Clears the "Bytes received/sent" counters.
Send break Sends a break signal to the device.
Send CTRL-P Sends CTRL-P to the device. It is not sent when
the menus are entered. CTRL-P is DLE, decimal #16,
hex $10, octal &020.
Reset font Changes the CLI/Shell font to plain (no bold,
underline, reverse etc.).
Clear screen Clears the screen and returns back to terminal
mode.
Reset modem Resets the modem with the Hayes command "ATZ".
Hangup line Hangs up line using the Hayes commands. Three
plus signs (+) are sent first, followed by a delay
of approx. 3 seconds, after which "ATH" is sent.
Upload Starts the program you've specified as the
uploader. Normally SZ.
Download Starts the program you've specified as the
downloader. Normally RZ.
Dialer Goes to the phonebook and autodialer. Explained
later.
Preferences Allows you to change the communication parameters
of the port and some terminal settings. These and
other functions are described below.
Open capture Asks for the filename for the capture. All input
from the device will be copied to this capture
file. If the file already exists, the new stuff
will be appended.
Close capture Closes the capture file.
Program and author Displays some information on the program and
information author.
Quit Quits ShellTerm.
Exit menus Exits the menus and returns "online".
6.2 Dialer menu
~~~~~~~~~~~~~~~
0 - 9 These keys select or deselect entries 1 - 10.
Relist entries Shows the entries (numbers) in the phonebook.
Single dial Asks "Number to dial:". Enter the number you would
like to dial.
Dial list Dials the entries selected from the phonebook.
Clear list Deselects all entries from list.
All Selects all entries from list for dialing.
Edit mode Enters edit mode. When this mode is on and an
entry is selected, the number for this entry is
asked. To turn it off, select a second time.
Prefix Asks for the dial prefix.
Main menu Goes back to the main menu.
Exit menus Exits the menus and returns "online".
6.3 Preferences menu
~~~~~~~~~~~~~~~~~~~~
Serial settings Goes to the serial settings menu. Described
below.
Terminal settings Goes to the terminal settings menu. Described
below.
Reset settings Reset settings to defaults: 9600, 8N1, no
translating and no BS & DEL swapping.
View settings Shows the current settings. NOTE! These might
be incorrect if a change of some item could not
be made. Currently the device name and unit will
show the device that couldn't be opened.
Load prefs Loads the preferences and phonebook.
Write prefs Saves the preferences and phonebook.
Name prefsfile Names the file used with load and save.
Upload program Asks for the external program that is to be run for
uploads. Normally this is a program called SZ (as
on *N*X machines).
Download program Asks for the external program that is to be run for
downloads. Normally this is a program called RZ (as
on *N*X machines).
Upload dir(ectory) The directory to CD to before uploads. If not
found/specified the current directory will be used.
Download dir(ectory) The directory to CD to before downloads. If not
found/specified the current directory will be used.
Assign CTRL-P With this, you can assign CTRL-P to any key. The
ASCII code of the will be displayed in 'View
settings'. When you have assigned CTRL-P to
some key, you can send the CTRL-P sequence over
to the device with the key you assigned.
Main menu Goes back to the main menu.
Exit menus Exits the menus and returns "online".
6.4 Terminal settings
~~~~~~~~~~~~~~~~~~~~~
CR translate, OUT Describes what to do every time a CR is to be sent.
Asks "(N)one, (S)trip, (A)dd LF:". If 'None' is
selected, a CR is sent. If 'Strip' is selected,
nothing is sent. If 'Add LF' is selected a CR and
an LF is sent.
LF translate, OUT Describes what to do every time an LF is to be sent.
Asks "(N)one, (S)trip, (A)dd CR:". If 'None' is
selected, an LF is sent. If 'Strip' is selected,
nothing is sent. If 'Add CR' is selected a CR and
an LF is sent.
CR translate, IN The same as "CR translate, OUT" except it
affects characters coming from the device to
the CLI/Shell.
LF translate, IN The same as "LF translate, OUT" except it
affects characters coming from the device to
the CLI/Shell.
Local echo Toggles local echo on/off. If enabled, everything
typed into the CLI will be displayed. Default is
off.
Swap BS & DEL Swaps BackSpace and DELete, when they are
entered into the CLI/Shell.
Ansi mode When this is set on, the screen will be cleared
before the menus are shown.
Cursor remap Remaps the Amiga cursor keys as 'EMACS cursor
keys'. I'm not sure if this totally true, since
tcsh etc. also use these. But then again there
might be an EMACS standard.
Previous menu Goes to the previous menu, Preferences.
Main menu Goes back to the main menu.
Exit menus Exits the menus and returns "online".
6.5 Serial settings
~~~~~~~~~~~~~~~~~~~
Speed Pressing a key from 0 through 9 will change the
speed used on the device. Possible speeds are:
(1) 110 bps (2) 300 bps
(3) 1200 bps (4) 2400 bps
(5) 4800 bps (6) 9600 bps
(7) 19 200 bps (8) 38 400 bps
(9) 57 600 bps (0) 115 200 bps
If someone REALLY REALLY REALLY (You get the
point) needs it, I can change the code to ask
for the baud/bps rate (I think you've guessed
that you will have to pay the shareware fee
to get this done.)
Name and Unit Asks for the device name and unit. After they've
been given, ShellTerm tries to open it.
Re-open device This will close the device and try to re-open it.
Set databits Toggles between 7 and 8 databits.
Set stopbits Toggles between 1 and 2 stopbits.
XON/XOFF Turns XON/XOFF handshaking on and off. NOT TESTED!
Previous menu Goes to the previous menu, Preferences.
Main menu Goes back to the main menu.
Exit menus Exits the menus and returns "online".
7. THE PHONEBOOK
~~~~~~~~~~~~~~~~
ShellTerm has a phonebook and autodialer. The phonebook file is currently
the same file as the preferences file (changed for version 1.06)
'S:ShellTerm.PREFS'. As of version (well, at least IN version) 1.06 the
phonebook entries are entered with the program itself. Go to the autodialer
and turn the edit mode on. Then select the entry you wish to edit/give the
number to. When you're finished just turn of the edit mode and dial away.
If you wish to save the phonebook, you'll have to go to the preferences
menu and select 'Save prefs'.
8. HINTS & TIPS
~~~~~~~~~~~~~~~
1. A scrollback buffer is available simply by using the Console Buffer
program by William J. Fritz (CB is Copyright (c) 1990 by William J. Fritz).
2. If you use my RingDetect program see its docs to see how to quit the
program from a script and how to restart it again after quitting ShellTerm.
On a multi-user Amiga (like mine), each user can have their own
prefs-file by simply making an alias in their '.login' file or the global
'.login' file. You can use something like this:
alias st $home/.strc
Where 'st' will be the alias that starts ShellTerm, '$home' a variable to
the users home directory and '.strc' the name of the prefs file.
3. To emulate 'Quiet' mode, simply enter the menus.
4. To do downloads / uploads use one of the RZ and SZ commands available.
Different protocols are widely available. RZ and SZ are for ZModem
transfers.
5. To use a *N*X, through modem or otherwise, use the ANSI termcap:
set term = ansi
setenv TERM ansi
or
tset ansi
This way the Shell will display things correctly (including IRC!). It works
at least on BSD systems.
6. To make sure the modem doesn't hang up if you quit ShellTerm for some
purpose, set the modem to not hang up when DTR is dropped.
7. A program called WatchPort is included with the ShellTerm archive.
Thanks go to Klaus Seistrup for this program. It will allow a script to
wait for ShellTerm to quit before continuing. A short quote from him:
---Cut Here---
"Now, my plans for the port of ShellTerm is to use it as an identifier to
decide when to return to TrapDoor again. I imagine something like this
might do it:
FKey "7:SPAWN \"Execute S:ShellTerm.launch\""
and the script S:ShellTerm.launch:
NewShell CON:blah/blah/blah FROM S:ShellTerm.bat
WatchPort ShellTerm_MyPort1
And S:ShellTerm.bat contains just one line:
ShellTerm PORT=ShellTerm_MyPort1
"
---Cut Here---
He uses this combination with trapdoor. It is of course possible to use it
with other programs that require waiting. See HINTS & TIPS 8.
8. To open ShellTerm on its own screen, open a public screen with your
favorite public screen manager and use a script like the one included in
this archive in the directory ShellTerm/Scripts.
9. PROBLEMS
~~~~~~~~~~~
The program reads and writes characters to and from the selected serial
device. If however you have a BBS software, or any other program that
uses the same device, most characters will go to the other program. You
may not notice this if you go straight to the dialer and start dialing.
I have often started to wonder what bug i've managed to get into the
dialer when it won't recognize a busy... After some debugging I
realized that half of the characters were going to another task!
There will most likely be a problem with high speed modems. I doubt very
much that ShellTerm will keep up with USRobotics (R) HST modems. I don't
even want to think of the new V.FAST that's coming!
10. OTHER INTERESTING STUFF
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
ShellTerm was written in assembler with the one and only Cygnus Editor. It
was compiled with A68k and Blink. The size of the source code is ~63000
bytes, equalling ~3200 lines of code. It is lightly commented. The version
number is bumped up every time I feel like it, which is usually when I get
bored of adding things, have found a bug or feel like releasing the whole
thing.
11. ERROR MESSAGES
~~~~~~~~~~~~~~~~~~
The ShellTerm program will display necessary error messages. I HATE
PROGRAMS THAT DON'T TELL WHAT-THE-HELL IS GOING ON! That clear? If
ShellTerm doesn't give any output, something is seriously wrong or
I was lazy :). The only thing ShellTerm won't report is that it won't run
on anything under 2.04. It will simply quit returning a failure number.
12. VERSIONS
~~~~~~~~~~~~
Version Size Date Description
----------------------------------------------------------------------
1.19 22600 26/05/93 Added a version number to the prefs file. I
also added some empty space so newer versions
will load older prefs files until a radical
change happens in it.
Added some stuff to the docs.
1.18 22596 22/05/93 Added scripts to archive. Added XON/XOFF, but
never tested it. Fixed the bug with setting
parameters. Changed a lot of code that had to
do with opening/closing devices, creating/
deleting Requests/MsgPorts.
1.17 21864 25/03/93 Added possibility to open a port with a
specific name. It is specified when ShellTerm
is run and not in the prefs file! This is to
save the trouble of making separate prefs
files for every application.
1.16 21736 24/03/93 Fixed a major bug in the routine that opens
the device. ShellTerm should now work on
multiple serial boards and maybe some other
exotic devices.
1.15 21828 10/02/93 The dialer won't be in Edit mode if quit.
Thus you won't accidentally erase an entry
if you first quit the dialer (while in edit
mode) and then come back to dial.
1.14 ~22000 06/02/93 Fixed a bug in the parser. Had to press
<ENTER> twice if using CSH (I accidentally
cleared the last byte of the CLI-args).
1.13 21808 02/01/93 Added 'Execute' option.
1.12 21668 01/01/93 Release 3. All bugs should be fixed. Should
work on all machines, not sure about dnet.
Changed the parser to stand up to Commodore's
guidelines.
1.11 ~22000 13/11/92 Private registered copy.
1.10 ~22000 20/10/92 Added public ports. Bug fixes.
1.09 21632 06/09/92 Release 2.
Docs checked.
1.08 ~22000 04/09/92 Added: Cursor remap.
Minor optimization.
1.07 ~21000 30/08/92 Tried to get this version out as a release.
Docs updated a bit more and added 'Hints &
Tips'.
Added: Upload/Download programs and dirs,
capture file.
1.06 ~18000 28/08/92 Bugs fixed. The dialer should work, toggling
between (data/stop)bits are shown correctly
even if the operation fails, added a greater
delay while dialing a list/single entry
(at least my phone line couldn't keep up)
Added: 'Send Break', preferences file, 'Swap
BS & DEL', Phonebook entry editor, assigning
of CTRL-P to a key.
Docs updated.
1.05 16116 14/08/92 Bugs fixed: Send CTRL-P works now.
1.04 16116 11/08/92 Bugs fixed: Dialer now knows about NO CARRIER
and dials after removing an entry.
Added: Clear screen and Reset font.
Release version. Forgot to check the docs :(
1.03 ~16000 08/08/92 Bugs fixed: Dialer should recognize the BUSY
and CONNECT texts from the modem now.
Minor optimization.
The next version should be a release :)
1.02 ~17000 06/08/92 Bugs fixed: Input is now flushed on starting
to prevent ugly things from happening when
going into the menus and there has been
options on the CMDline.
Added: Preferences (local echo, speed CR/LF
translating, data & stop bits)
Minor optimization.
1.01 ~10000 05/08/92 A beta tester version, now with phonebook.
1.00 ???? 04/08/92 A simple version without many bugs and quite
slow.
0.00a- ???? ??/??/92 Wrote the program basics and main routines.
0.99a
13. FUTURE VERSIONS
~~~~~~~~~~~~~~~~~~~
Future version will have the bug fixes for the bugs I haven't found and you
have :). And if some really needs to use this with the dnet.device (as I've
heard), mail me some info on it etc. I'll look into it myself if I find the
time. I have also been pressed towards adding a VT100 emulation... This I'm
afraid is not going to happen, at least yet... :(. A log for the dialer is
also one idea I have.
14. BUGS
~~~~~~~~
ShellTerm has been run with enforcer and mungwall. It will be run with devmon
as soon as I can find it again :). In other words, I haven't found any
bugs, so this part in the docs is totally useless! :)
15. SHAREWARE FEE
~~~~~~~~~~~~~~~~~
As of version 1.04, ShellTerm is ShareWare. I am not asking for a huge
amount of money so I hope I will get some response. The fee is only $5 to
$10 (USD), or whatever that happens to make at the moment you're reading
this, in german marks (DM). If you're from Finland a sum of 20 FIM to 50
FIM is great (Yeah, so what if I changed the $10 to $12 ? You Finnish guys
don't have to pay so much for postage :). Any amount in Coca-Cola (TM) will
also do.
16. BETA TESTERS
~~~~~~~~~~~~~~~~
Thank you all who beta tested ShellTerm. Thanks go to Radix (thank you for
the Clear Screen and Reset font ideas), Forge, mlelstv, Arc, Jasper and
jlaine and MKsa (for the Swap BS & DEL idea and the others i haven't
implemented). If you wish to become a beta tester contact me at one of the
addresses below. If a beta tester wishes to be anonymous or the opposite,
wishes their full name to be listed, please let me know!
17. 'REGISTERED' USERS
~~~~~~~~~~~~~~~~~~~~~~
Anyone who pays will get their name here if they wish so.
Klaus Seistrup -Paid with WatchPort
18. BUG REPORTS ETC...
~~~~~~~~~~~~~~~~~~~~~~
Please send donations, bug reports, and list of features you would like to
have included in future versions to
Tomi Blinnikka
Syystie 10
00780 Helsinki
FINLAND
Contact me at the address above or on the following BBS:
MITS +358-0-458 2066 (MITS - Microdata International Telecomm Service)
MITS +358-0-458 2077
MITS +358-0-458 2088 (Sec. level 40 or higher ONLY)
Email me at 'docbliny@mits.mdata.fi' or catch me on the #amiga conference
on IRC!
"...trademark of Xerox Corporations. Reading legal mush can turn your
brain to guacamole! Epson is registered trademark of Epson America
..." -Amiga RKRM Includes & AutoDocs, fourth page.
Tomi Blinnikka
docbliny@mits.mdata.fi